Extension Development Guide

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

10. Appendices

This guide provides a comprehensive walkthrough for developing browser extensions using the WXT framework. It covers environment setup, configuration, build processes, TypeScript setup, component development patterns, testing strategies, packaging and distribution, cross-browser compatibility, debugging techniques, and performance optimization. It also includes practical examples for adding new components, extending functionality, and integrating with backend services.

The extension is organized around WXT entrypoints and React components:

• Entry points: background service worker, content script, sidepanel UI, and popup UI

• Sidepanel UI built with React, Shadow DOM injection, and custom hooks

• Shared utilities and WebSocket client integration

• Build and configuration managed via WXT and TypeScript

Diagram sources

• background.ts

• content.ts

• index.tsx

• App.tsx

• popup.tsx

• useAuth.ts

• useTabManagement.ts

• useWebSocket.ts

• UnifiedSettingsMenu.tsx

• ApiKeySection.tsx

• wxt.config.ts

• package.json

• tsconfig.json

• .wxt/tsconfig.json

Section sources

• wxt.config.ts

• package.json

• tsconfig.json

• .wxt/tsconfig.json

• README.md

• WXT configuration defines module support, manifest metadata, permissions, and host permissions.

• TypeScript configuration extends WXT’s internal tsconfig, enabling JSX and path aliases.

• Package scripts orchestrate development, building, and packaging for multiple browsers.

• Entry points:

  • background.ts: message routing, tab management, agent tool execution, Gemini integration

  • content.ts: optional page overlay and action execution helpers

  • sidepanel/index.tsx: mounts React app into shadow DOM

  • popup/popup.tsx: tab list UI and activation/deactivation messaging

• React hooks encapsulate authentication, tab management, and WebSocket connectivity.

• Settings menu integrates model selection, API keys, base URLs, and credential storage.

Section sources

• wxt.config.ts

• tsconfig.json

• .wxt/tsconfig.json

• package.json

• background.ts

• content.ts

• index.tsx

• popup.tsx

• useAuth.ts

• useTabManagement.ts

• useWebSocket.ts

• UnifiedSettingsMenu.tsx

• ApiKeySection.tsx

The extension follows a MV3 architecture with a background service worker coordinating messaging, tab operations, and agent tool execution. The sidepanel UI runs in a Shadow DOM, communicating with the background via runtime messages. Optional content script provides page-level actions and overlays.

Diagram sources

• popup.tsx

• index.tsx

• App.tsx

• background.ts

• content.ts

WXT Configuration and Build#

• Modules: React module enabled for seamless integration.

• Manifest: Name, description, permissions, and host permissions configured.

• Scripts: dev, build, zip, and compile commands for Chrome and Firefox targets.

Section sources

• wxt.config.ts

• package.json

TypeScript Configuration#

• Root tsconfig extends WXT’s internal tsconfig.

• Compiler options enable JSX with React JSX transform, path aliases, and strictness.

• WXT internal tsconfig sets module resolution, strictness, and includes/excludes.

Section sources

• tsconfig.json

• .wxt/tsconfig.json

Sidepanel Entry Point and Shadow DOM Injection#

• Defines a content script with matches for all URLs and Shadow DOM UI mounting.

• Creates a named UI with inline positioning and lifecycle hooks for mounting/unmounting.

Section sources

• index.tsx

Sidepanel Application and State Management#

• Orchestrates authentication, tab management, WebSocket connectivity, and settings.

• On mount, activates AI frame in the active tab and listens to storage changes.

• Loads API key and conversation stats, with fallbacks to HTTP when WebSocket is unavailable.

Section sources

• App.tsx

• App.tsx

• App.tsx

Authentication Hook#

• Handles browser identity launch flow, token exchange, refresh logic, and storage updates.

• Provides token age/expiry calculations and manual refresh capability.

• Supports demo GitHub login bypass for development.

Section sources

• useAuth.ts

• useAuth.ts

• useAuth.ts

Tab Management Hook#

• Subscribes to tab events and maintains active tab state.

• Requests all tabs from background and updates UI accordingly.

Section sources

• useTabManagement.ts

• useTabManagement.ts

WebSocket Hook#

• Manages connection status and auto-connect preferences.

• Integrates with a WebSocket client to receive progress updates and status changes.

Section sources

• useWebSocket.ts

• useWebSocket.ts

• useWebSocket.ts

Unified Settings Menu#

• Provides tabs for Settings and Profile.

• Settings include model selection, API key management, base URL configuration, and auto-connect toggle.

• Profile includes token status, manual refresh, logout, and credential storage.

Section sources

• UnifiedSettingsMenu.tsx

• UnifiedSettingsMenu.tsx

• UnifiedSettingsMenu.tsx

API Key Section Component#

• Simple controlled input for API key with save action.

Section sources

• ApiKeySection.tsx

Background Service Worker#

• Message router for agent tool execution, tab activation/deactivation, tab queries, action execution, Gemini requests, and generated agent runs.

• Implements robust async handlers with error propagation.

• Tab tracking listeners update stored tab information.

Section sources

• background.ts

• background.ts

Content Script#

• Optional overlay creation and removal helpers.

• Action execution helpers for play/pause video, click buttons, fill forms, scroll, and page info retrieval.

Section sources

• content.ts

• content.ts

Popup UI#

• Displays active tab and all tabs fetched from storage.

• Activates AI frame on mount and deactivates on cleanup.

Section sources

• popup.tsx

• popup.tsx

The extension relies on WXT for build and manifest generation, React for UI, and browser extension APIs for messaging, tabs, storage, and scripting. Hooks encapsulate cross-cutting concerns and promote reuse.

Diagram sources

• package.json

• wxt.config.ts

• tsconfig.json

• .wxt/tsconfig.json

• background.ts

• content.ts

• index.tsx

• App.tsx

• popup.tsx

• useAuth.ts

• useTabManagement.ts

• useWebSocket.ts

• UnifiedSettingsMenu.tsx

• ApiKeySection.tsx

Section sources

• package.json

• wxt.config.ts

• tsconfig.json

• .wxt/tsconfig.json

• Minimize DOM manipulations in content scripts; batch updates and avoid frequent reflows.

• Debounce tab event listeners to reduce unnecessary storage writes.

• Prefer lazy initialization for heavy modules (e.g., dynamic imports for Gemini SDK).

• Use WebSocket for real-time updates; fall back to HTTP polling gracefully.

• Keep Shadow DOM UI lightweight; defer heavy computations to background or content contexts.

• Avoid excessive background memory retention; clean up listeners and timers on unmount.

Common issues and resolutions:

• Storage change listener signature: Ensure the listener accepts two parameters (changes, areaName) to prevent runtime crashes.

• Background message routing: Verify message types match between sender and receiver; log unknown types for diagnostics.

• Tab activation/deactivation: Confirm tab IDs are present before sending messages; handle errors silently to avoid blocking UI.

• Authentication flow: Validate redirect URIs and scopes; ensure backend endpoints are reachable during token exchange.

• WebSocket connectivity: Implement auto-reconnect logic and fallback to HTTP when disconnected.

Section sources

• popup.tsx

• background.ts

• App.tsx

• useAuth.ts

This guide outlined the WXT-based extension architecture, configuration, and development patterns. By leveraging React hooks, Shadow DOM UI, and a robust background service worker, the extension achieves modular, maintainable, and scalable functionality. Following the provided practices ensures reliable builds, cross-browser compatibility, and efficient performance.

Development Environment Setup#

• Install dependencies using the package manager configured in the project.

• Run development servers for Chrome and Firefox using WXT scripts.

• Use TypeScript compilation checks to validate type safety.

Section sources

• package.json

• README.md

Build and Packaging#

• Build for Chrome and Firefox using WXT build scripts.

• Generate ZIP archives for distribution using WXT zip scripts.

• Compile TypeScript without emitting to validate types.

Section sources

• package.json

Cross-Browser Compatibility#

• Permissions and APIs vary slightly across browsers; test on Chrome and Firefox.

• Use browser-specific APIs judiciously and provide fallbacks where necessary.

• Validate manifest entries and permissions in each target browser.

Testing Strategies#

• Unit test hooks and utilities using a testing framework compatible with browser APIs.

• Snapshot test React components to detect layout regressions.

• End-to-end test message flows between popup, sidepanel, and background.

• Mock external services (e.g., Gemini, backend endpoints) for deterministic tests.

Extension Store Submission and Security Review#

• Provide accurate metadata in the manifest (name, description, icons).

• Limit permissions to only those required for core functionality.

• Include privacy policy and terms of service links.

• Ensure secure handling of tokens and credentials; never expose secrets in client-side code.

• Implement secure communication with backend services (HTTPS, token refresh, short-lived tokens).

Debugging Techniques#

• Enable developer mode in the target browser and load unpacked extensions.

• Inspect background/service worker logs for message routing and errors.

• Use React DevTools to inspect component state and props in the sidepanel UI.

• Monitor network requests and WebSocket connections for integration issues.

Development Workflow Optimization#

• Use incremental builds and hot reloading during development.

• Organize components into reusable hooks and shared UI elements.

• Centralize configuration (permissions, endpoints) in WXT config and environment variables.

• Automate linting and formatting to maintain code quality.